Linux Cubed Series 3: Developer Tools

home *** CD-ROM | disk | FTP | other *** search

/ Linux Cubed Series 3: Developer Tools / Linux Cubed Series 3 - Developer Tools.iso / devel / lang / lisp / guile-ii.src / guile-ii / guile-src / guile-docs / user / scm.info-3 < prev next >

Wrap

GNU Info File | 1995-06-08 | 48.7 KB | 1,266 lines

This is Info file scm.info, produced by Makeinfo-1.55 from the input file scm.texi. File: scm.info, Node: Window Manipulation, Next: Output, Prev: Terminal Mode Setting, Up: Curses Window Manipulation ------------------- - Function: newwin NLINES NCOLS BEGY BEGX Create and return a new window with the given number of lines (or rows), NLINES, and columns, NCOLS. The upper left corner of the window is at line BEGY, column BEGX. If either NLINES or NCOLS is 0, they will be set to the value of `LINES'-BEGY and `COLS'-BEGX. A new full-screen window is created by calling `newwin(0,0,0,0)'. - Function: subwin ORIG NLINES NCOLS BEGY BEGX Create and return a pointer to a new window with the given number of lines (or rows), NLINES, and columns, NCOLS. The window is at position (BEGY, BEGX) on the screen. This position is relative to the screen, and not to the window ORIG. The window is made in the middle of the window ORIG, so that changes made to one window will affect both windows. When using this routine, often it will be necessary to call `touchwin' or `touchline' on ORIG before calling `force-output'. - Function: close-port WIN Deletes the window WIN, freeing up all memory associated with it. In the case of sub-windows, they should be deleted before the main window WIN. - Function: refresh - Function: force-output WIN These routines are called to write output to the terminal, as most other routines merely manipulate data structures. `force-output' copies the window WIN to the physical terminal screen, taking into account what is already there in order to minimize the amount of information that's sent to the terminal (called optimization). Unless `leaveok' has been enabled, the physical cursor of the terminal is left at the location of window WIN's cursor. With `refresh', the number of characters output to the terminal is returned. - Function: mvwin WIN Y X Move the window WIN so that the upper left corner will be at position (Y, X). If the move would cause the window WIN to be off the screen, it is an error and the window WIN is not moved. - Function: overlay SRCWIN DSTWIN - Function: overwrite SRCWIN DSTWIN These routines overlay SRCWIN on top of DSTWIN; that is, all text in SRCWIN is copied into DSTWIN. SRCWIN and DSTWIN need not be the same size; only text where the two windows overlap is copied. The difference is that `overlay' is non-destructive (blanks are not copied), while `overwrite' is destructive. - Function: touchwin WIN - Function: touchline WIN START COUNT Throw away all optimization information about which parts of the window WIN have been touched, by pretending that the entire window WIN has been drawn on. This is sometimes necessary when using overlapping windows, since a change to one window will affect the other window, but the records of which lines have been changed in the other window will not reflect the change. `touchline' only pretends that COUNT lines have been changed, beginning with line START. - Function: wmove WIN Y X The cursor associated with the window WIN is moved to line (row) Y, column X. This does not move the physical cursor of the terminal until `refresh' (or `force-output') is called. The position specified is relative to the upper left corner of the window WIN, which is (0, 0). File: scm.info, Node: Output, Next: Input, Prev: Window Manipulation, Up: Curses Output ------ These routines are used to "draw" text on windows - Function: display CH WIN - Function: display STR WIN - Function: wadd WIN CH - Function: wadd WIN STR The character CH or characters in STR are put into the window WIN at the current cursor position of the window and the position of WIN's cursor is advanced. At the right margin, an automatic newline is performed. At the bottom of the scrolling region, if scrollok is enabled, the scrolling region will be scrolled up one line. If CH is a TAB, LFD, or backspace, the cursor will be moved appropriately within the window WIN. A LFD also does a `wclrtoeol' before moving. TAB characters are considered to be at every eighth column. If CH is another control character, it will be drawn in the `C-x' notation. (Calling `winch' after adding a control character will not return the control character, but instead will return the representation of the control character.) Video attributes can be combined with a character by or-ing them into the parameter. This will result in these attributes also being set. The intent here is that text, including attributes, can be copied from one place to another using inch and display. See `standout', below. *Note:* For `wadd' CH can be an integer and will insert the character of the corresponding value. - Function: werase WIN This routine copies blanks to every position in the window WIN. - Function: wclear WIN This routine is like `werase', but it also calls *Note clearok: Output Options Setting, arranging that the screen will be cleared completely on the next call to `refresh' or `force-output' for window WIN, and repainted from scratch. - Function: wclrtobot WIN All lines below the cursor in window WIN are erased. Also, the current line to the right of the cursor, inclusive, is erased. - Function: wclrtoeol WIN The current line to the right of the cursor, inclusive, is erased. - Function: wdelch WIN The character under the cursor in the window WIN is deleted. All characters to the right on the same line are moved to the left one position and the last character on the line is filled with a blank. The cursor position does not change. This does not imply use of the hardware "delete-character" feature. - Function: wdeleteln WIN The line under the cursor in the window WIN is deleted. All lines below the current line are moved up one line. The bottom line WIN is cleared. The cursor position does not change. This does not imply use of the hardware "deleteline" feature. - Function: winsch WIN CH The character CH is inserted before the character under the cursor. All characters to the right are moved one SPC to the right, possibly losing the rightmost character of the line. The cursor position does not change . This does not imply use of the hardware "insertcharacter" feature. - Function: winsertln WIN A blank line is inserted above the current line and the bottom line is lost. This does not imply use of the hardware "insert-line" feature. - Function: scroll WIN The window WIN is scrolled up one line. This involves moving the lines in WIN's data structure. As an optimization, if WIN is stdscr and the scrolling region is the entire window, the physical screen will be scrolled at the same time. File: scm.info, Node: Input, Next: Curses Miscellany, Prev: Output, Up: Curses Input ----- - Function: read-char WIN A character is read from the terminal associated with the window WIN. Depending on the setting of `cbreak', this will be after one character (`CBREAK' mode), or after the first newline (`NOCBREAK' mode). Unless `noecho' has been set, the character will also be echoed into WIN. When using `read-char', do not set both `NOCBREAK' mode (`nocbreak') and `ECHO' mode (`echo') at the same time. Depending on the state of the terminal driver when each character is typed, the program may produce undesirable results. - Function: winch WIN The character, of type chtype, at the current position in window WIN is returned. If any attributes are set for that position, their values will be OR'ed into the value returned. - Function: getyx WIN A list of the y and x coordinates of the cursor position of the window WIN is returned File: scm.info, Node: Curses Miscellany, Prev: Input, Up: Curses Curses Miscellany ----------------- - Function: wstandout WIN - Function: wstandend WIN These functions set the current attributes of the window WIN. The current attributes of WIN are applied to all characters that are written into it. Attributes are a property of the character, and move with the character through any scrolling and insert/delete line/character operations. To the extent possible on the particular terminal, they will be displayed as the graphic rendition of characters put on the screen. `wstandout' sets the current attributes of the window WIN to be visibly different from other text. `wstandend' turns off the attributes. - Function: box WIN VERTCH HORCH A box is drawn around the edge of the window WIN. VERTCH and HORCH are the characters the box is to be drawn with. If VERTCH and HORCH are 0, then appropriate default characters, `ACS_VLINE' and `ACS_HLINE', will be used. *Note:* VERTCH and HORCH can be an integers and will insert the character (with attributes) of the corresponding values. - Function: unctrl C This macro expands to a character string which is a printable representation of the character C. Control characters are displayed in the `C-x' notation. Printing characters are displayed as is. File: scm.info, Node: Sockets, Prev: Curses, Up: Packages Sockets ======= These procedures (defined in `socket.c') provide a Scheme interface to most of the C "socket" library. For more information on sockets, *Note Sockets: (libc)Sockets. * Menu: * Host Data:: * Internet Addresses:: * Socket:: File: scm.info, Node: Host Data, Next: Internet Addresses, Prev: Sockets, Up: Sockets Host Data, Network, Protocol, and Service Inquiries --------------------------------------------------- - Constant: af_inet - Constant: af_unix Integer family codes for Internet and Unix sockets, respectively. - Function: gethost HOST-SPEC - Function: gethost Returns a vector of information for the entry for `HOST-SPEC' or the next entry if `HOST-SPEC' isn't given. The information is: 0. host name string 1. list of host aliases strings 2. integer address type (`AF_INET') 3. integer size of address entries (in bytes) 4. list of integer addresses - Function: sethostent STAY-OPEN - Function: sethostent Rewinds the host entry table back to the begining if given an argument. If the argument STAY-OPEN is `#f' queries will be be done using `UDP' datagrams. Otherwise, a connected `TCP' socket will be used. When called without an argument, the host table is closed. - Function: getnet NAME-OR-NUMBER - Function: getnet Returns a vector of information for the entry for NAME-OR-NUMBER or the next entry if an argument isn't given. The information is: 0. official network name string 1. list of network aliases strings 2. integer network address type (`AF_INET') 3. integer network number - Function: setnetent STAY-OPEN - Function: setnetent Rewinds the network entry table back to the begining if given an argument. If the argument STAY-OPEN is `#f' the table will be closed between calls to getnet. Otherwise, the table stays open. When called without an argument, the network table is closed. - Function: getproto NAME-OR-NUMBER - Function: getproto Returns a vector of information for the entry for NAME-OR-NUMBER or the next entry if an argument isn't given. The information is: 1. official protocol name string 2. list of protocol aliases strings 3. integer protocol number - Function: setprotoent STAY-OPEN - Function: setprotoent Rewinds the protocol entry table back to the begining if given an argument. If the argument STAY-OPEN is `#f' the table will be closed between calls to getproto. Otherwise, the table stays open. When called without an argument, the protocol table is closed. - Function: getserv NAME-OR-PORT-NUMBER PROTOCOL - Function: getserv Returns a vector of information for the entry for NAME-OR-PORT-NUMBER and PROTOCOL or the next entry if arguments aren't given. The information is: 0. official service name string 1. list of service aliases strings 2. integer port number 3. protocol - Function: setservent STAY-OPEN - Function: setservent Rewinds the service entry table back to the begining if given an argument. If the argument STAY-OPEN is `#f' the table will be closed between calls to getserv. Otherwise, the table stays open. When called without an argument, the service table is closed. File: scm.info, Node: Internet Addresses, Next: Socket, Prev: Host Data, Up: Sockets Internet Addresses ------------------ - Function: inet:string->address STRING Returns the host address number (integer) for host STRING or `#f' if not found. - Function: inet:address->string ADDRESS Converts an internet (integer) address to a string in numbers and dots notation. This is an inverse function to inet:address. - Function: inet:network ADDRESS Returns the network number (integer) specified from ADDRESS or `#f' if not found. - Function: inet:local-network-address ADDRESS Returns the integer for the address of ADDRESS within its local network or `#f' if not found. - Function: inet:make-address NETWORK LOCAL-ADDRESS Returns the Internet address of LOCAL-ADDRESS in NETWORK. File: scm.info, Node: Socket, Prev: Internet Addresses, Up: Sockets Socket ------ When a port is returned from one of these calls it is unbuffered. This allows both reading and writing to the same port to work. If you want buffered ports you can (assuming sock-port is a socket i/o port): (require 'i/o-extensions) (define i-port (duplicate-port sock-port "r")) (define o-port (duplicate-port sock-port "w")) - Function: make-stream-socket FAMILY - Function: make-stream-socket FAMILY PROTOCOL Returns a `SOCK_STREAM' socket of type FAMILY using PROTOCOL. If FAMILY has the value `AF_INET', `SO_REUSEADDR' will be set. The integer argument PROTOCOL corresponds to the integer protocol numbers returned (as vector elements) from `(getproto)'. If the PROTOCOL argument is not supplied, the default (0) for the specified FAMILY is used. SCM sockets look like ports opened for neither reading nor writing. - Function: make-stream-socketpair FAMILY - Function: make-stream-socketpair FAMILY PROTOCOL Returns a pair (cons) of connected `SOCK_STREAM' (socket) ports of type FAMILY using PROTOCOL. Many systems support only socketpairs of the `af-unix' FAMILY. The integer argument PROTOCOL corresponds to the integer protocol numbers returned (as vector elements) from (getproto). If the PROTOCOL argument is not supplied, the default (0) for the specified FAMILY is used. - Function: socket:shutdown SOCKET HOW Makes SOCKET no longer respond to some or all operations depending on the integer variable HOW: 0. Further input is disallowed. 1. Further output is disallowed. 2. Further input or output is disallowed. `Socket:shutdown' returns SOCKET if successful, `#f' if not. - Function: socket:connect INET-SOCKET HOST-NUMBER PORT-NUMBER - Function: socket:connect UNIX-SOCKET PATHNAME Returns SOCKET (changed to a read/write port) connected to the Internet socket on host HOST-NUMBER, port PORT-NUMBER or the Unix socket specified by PATHNAME. Returns `#f' if not successful. - Function: socket:bind INET-SOCKET PORT-NUMBER - Function: socket:bind UNIX-SOCKET PATHNAME Returns INET-SOCKET bound to the integer PORT-NUMBER or the UNIX-SOCKET bound to new socket in the file system at location PATHNAME. Returns `#f' if not successful. Binding a UNIX-SOCKET creates a socket in the file system that must be deleted by the caller when it is no longer needed (using `delete-file'). - Function: socket:listen SOCKET BACKLOG The bound (*note socket-bind: Sockets.) SOCKET is readied to accept connections. The positive integer BACKLOG specifies how many pending connections will be allowed before further connection requests are refused. Returns SOCKET if successful, `#f' if not. - Function: socket:accept SOCKET Accepts a connection on a bound, listening SOCKET. Returns an input/output port for the connection. For example: (let ((sock (socket:bind (make-stream-socket af_inet) 8001))) (socket:listen sock 5) (do ((connection (socket:accept sock) (socket:accept sock))) (#f) (handle-client-connection connection)))) A type "socket-name" is used for inquiries about open sockets in the following procedures: - Function: getsockname SOCKET Returns the socket-name of SOCKET. Returns `#f' if unsuccessful or SOCKET is closed. - Function: getpeername SOCKET Returns the socket-name of the socket connected to SOCKET. Returns `#f' if unsuccessful or SOCKET is closed. - Function: socket-name:family SOCKET-NAME Returns the integer code for the family of SOCKET-NAME. - Function: socket-name:port-number SOCKET-NAME Returns the integer port number of SOCKET-NAME. - Function: socket-name:address SOCKET-NAME Returns the integer Internet address for SOCKET-NAME. File: scm.info, Node: Guile Facilities, Next: Internals, Prev: Packages, Up: Top Guile Facilities **************** Using SCM as a base, GUILE is a being developed to be a GNU scripting language. One design goal of GUILE is to fully support a large body of Emacs lisp code and a large population of Emacs lisp programmers. GUILE accomplishes this goal by means of a translator that rewrites elisp programs as equivalent programs in extended GUILE Scheme. We anticipate a port of the GNU Emacs built-ins to the GUILE environment. Tom Lord (Lord@cygnus.com) is coordinating GUILE's development. * Menu: * Locked Vectors:: You can define the layout of new types. * Exceptions:: Cheap CATCH/THROW for errors and exits. * System Exceptions:: All error conditions can be caught by Scheme code. * Variables:: First class locatives for top level variables. * User Defined Top Levels:: You can control the symbol->variable mapping. * Obarrays:: First class tables for interning symbols. * Keywords:: * Procedure Properties:: * Dynamic Roots:: Creating uncapturable continuations. * Tcl Facilities:: Mutual calling between Tcl and Scheme. * Tk Facilities:: Accessing Tk from Scheme. * Gwish:: A Wish-like application of Guile. * System Calls:: You can choose to ignore errors safely. * Gscsh:: Shell and systems programming features. File: scm.info, Node: Locked Vectors, Next: Exceptions, Prev: Guile Facilities, Up: Guile Facilities Locked Vectors ============== Locked vectors "lvectors" are a low level means by which Scheme code can define the representation of new types. They are not themselves especially easy to use, but useful system can be built on top of them (for example, *note Records: (slib)Records.). User code should be selective about using lvector functions. Lvectors are intended as the representation for user-defined types. Types which otherwise have nothing to do with one another may have in common an lvector representation. Using lvector functions in a context other than defining a new type or family of types is likely to be an unsupported violation of abstractions - something you generally only want to do when you are debugging or are willing to write *hacked up* (in the pejorative sense) code. Locked vectors have an internal representation similar to vectors. They are represented by a contiguous array in memory. Access and modifications to fields can be done in constant time. Like vectors, fields of a locked vector are addressed by integer addresses, based at 0. The 0 element of a locked vector is special. It is called the "key vector". It's use is comparable to that of type objects in other systems. The key vector must always be present (there is no such thing as a 0 length lvector). It must be a (normal) vector with at least as many elements as the lvector. The elements of the key vector are used as keys which control access to the corresponding elements of the lvector. Keys are used this way: Procedures like lvector-ref and lvector-set! take a "key argument" in addition to the lvector and field index. The key argument is compared to the indexed element of the key vector. If they are the same (`eq?'), access to the lvector is granted. If an access or modification fails because of an incorrect key, it may be retried. If element 0 of the key vector is itself an lvector, the first several elements of that lvector may be hook functions. These hook functions are used to extend the behavior of built-in procedures. Hook functions are explained in more detail at the end of this section. * Menu: * Lvector Procedures:: * Key-Vector 0 Elements:: File: scm.info, Node: Lvector Procedures, Next: Key-Vector 0 Elements, Prev: Locked Vectors, Up: Locked Vectors Lvector Procedures ------------------ - Function: lock-vector! VEC Modify VEC so that it is a locked vector instead of a vector. Once it is locked, ordinary vector operations no longer apply to VEC, and `vector?' returns `#f' for VEC. In order to be locked, VEC must have at least one element. The 0 element of VEC must be a key vector (see above). `lock-vector!' is currently the only way to construct a locked vector. However, the decision to create locked vectors by mutating vectors is a dubious one. Therefore, you should only use lock-vector! by wrapping it around a vector constructor, as in: (lock-vector! (apply vector (cons key-vector field-inits))) Following this convention will make it easier to replace lock-vector! with a more reasonable constructor later. - Function: unlock-vector! LVEC Modify LVEC so that it is once again the vector passed to `lock-vector!'. You should only use `unlock-vector!' for debugging. It is not guaranteed to be present in future versions of Guile. - Function: lvector-ref LVEC KEY INDEX Return the INDEXth element of LVEC. If KEY matches the INDEXth element of the key vector of LVEC, then the INDEXth element of LVEC is returned. If the key does not match, then the `ref-fn' hook is tried (hooks are documented below). If the INDEXth element can not be unlocked, an error is signaled. - Function: lvector-set! LVEC KEY INDEX VAL Set the INDEXth element of LVEC. If KEY matches the INDEXth element of the key vector of LVEC, then the INDEXth element of LVEC is set. If the key does not match, then the `set-fn' hook is tried (see below). If the INDEXth element can not be unlocked, an error is signaled. - Function: lvector? OBJ True if OBJ is indeed a locked vector. - Function: lvector-keys LVEC Return the key vector of LVEC, a locked vector. - Function: lvector-accessor KEY-VEC INDEX Return an accessor for KEY-VEC and INDEX. This function is defined as: (define (lvector-accessor keyvec index) (lambda (lvec) (lvector-ref lvec (vector-ref keyvec index) index))) However, the built-in version returns an accessor function that is faster than what the above code would return. - Function: lvector-modifier KEY-VEC INDEX Return an modifier for KEY-VEC and INDEX. This function is defined as: (define (lvector-modifier keyvec index) (lambda (lvec val) (lvector-set! lvec (vector-ref keyvec index) index val))) However, the built-in version returns an modifier function that is faster than what the above code would return. - Function: lvector-isa? LVECTOR KEY-VECTOR Return `#t' if LVECTOR's 0th element is `eq?' to KEY-VECTOR. If KEY-VECTOR is not equal to element 0, lvector-isa? may yet return a true value - it returns the (arbitrary) return value of of the isa-fn?, if that hook is provided. File: scm.info, Node: Key-Vector 0 Elements, Prev: Lvector Procedures, Up: Locked Vectors Key-Vector 0 Elements --------------------- The first element of the key vector is special. It may refer to a number of hook functions used by the lvector procedures and other parts of the run time system. The 0 element of a key vector may (optionally) be an lvector called "the type lvector". A type lvector is characterized by having as a key the procedure `lvector-ref' for elements at offsets where hook functions are expected. The hook function offsets are bound to the variables LVECTOR-HOOK-<FN>; so the REF-FN is at the offset bound to LVECTOR-REF-FN, the SET-FN to LVECTOR-SET-FN and so on. The order and position of the hooks is explicitly specified: 1. ref-fn 2. set-fn 3. print-fn 4. equal-fn 5. isa-fn Here is how they are used: - Hook: ref-fn LVEC KEY INDEX This function is called by `lvector-ref' for illegal keys. A KEY is illegal if it is not `eq?' to the INDEXth key of the key vector of LVEC. The `ref-fn' hook may return a value for `lvector-ref' or can signal an error. The default action is to signal an error. - Hook: set-fn LVEC KEY INDEX VAL This function is called by `lvector-set!' for illegal keys. This hook can interpret the assignment arbitrarily, including signal an error. It can return a value for `lvector-set!'. The default action is to signal an error. - Hook: print-fn LVEC PORT WRITING? This function, if present, is called whenever the object is printed. It should print the object on PORT. WRITING?, if `#t', indicates that the value is being `write'n; if `#f' - `display'ed. The print function should return a true value if it succeeds. It should return `#f' for objects which it can not print. In that case, a generic print routine for "unknown objects" is used. The default action (if no PRINT-FN is supplied) is to print something like: `#<locked-vector 0x7856af8>'. - Predicate: equal-fn? LVEC LVEC2 If present, called to evaluate `(equal? lvec lvec2)'. The default action is a member-wise comparison of the two lvecs. Note that the first argument to `equal?' chooses the hook function. - Predicate: isa-fn? LVEC KEY-VECTOR If present, this may be called by `lvector-isa?'. If KEY-VECTOR is eq to lvecs key-vector, then `lvector-isa?' simply returns `#t'. If not, if the isa-fn is present, it is called. The default action is to return `#f'. Any of the hooks may be `#f' specifying that the default action should be used. - Variable: lvector-hook-slots The variable `lvector-hook-slots' is bound to the number of hook slots looked for by the run time system. A type lvector should have at least that many fields. Here is an illustration of the construction of lvectors. Note that two lvectors are built - one to hold the hook functions, and then the one for "user code". ;; Create a key vector compatible with the run-time system's ;; way of finding hook functions. ;; (define a-type-keyvec ;; The run-time system uses procedure lvector-ref as the key ;; to access hook functions. You could define type keyvecs ;; with more elements if you had a use for them. ;; (make-vector lvector-hook-slots lvector-ref)) ;; Lock up user-provided hook functions for the run-time system. ;; A var-args implementation would make more sense -- it would ;; make it easier to add hooks later. The example is written ;; this way just to provide a reference for the proper order ;; of hook functions within the lvector. ;; (define (make-type-lvector ref-hook set-hook print-hook equal-hook isa-hook) (lock-vector! (vector a-type-keyvec ref-hook set-hook print-hook equal-hook isa-hook))) ;; Turn a list of field keys into a key vector of a particular ;; type: ;; (define (make-key-vector type-lvector . field-keys) (apply vector (cons type-lvector field-keys))) ;; Turn a key-vector and list of field initializers into ;; a locked vector. Note that lock-vector! does some error ;; checking on the lengths of the input arguments. ;; (define (make-object key-vector . field-inits) (lock-vector! (apply (vector (cons key-vector field-inits))))) File: scm.info, Node: Exceptions, Next: System Exceptions, Prev: Locked Vectors, Up: Guile Facilities Exceptions ========== These are the low level entry points to exceptions. Individual subsystems may define their own uses for exceptions. - Function: catch KEY THUNK HANDLER Invoke THUNK in the dynamic context of HANDLER for excpetions matching KEY. If thunk throws to the symbol KEY, then HANDLER is invoked this way: (handler key args ...) KEY may be a symbol. In that case, THUNK takes no arguments. If THUNK returns normally, that is the return value of `catch'. Handler is invoked outside the scope of its own `catch'. If HANDLER against throws to the same key, a new handler from further up the call chain is invoked. If the key is #t, then a throw to any symbol will match this call to `catch'. Key may also be the value `#f'. In that case, THUNK takes one argument which will be passed a "jump buffer object". A jump buffer object may be used as the key argument to `throw' to throw to a specific `catch' without an intervening search for a symbolic key. - Function: throw KEY ARGS ... - Function: throw KEY Invoke the catch form matching KEY, passing ARGS to the HANDLER. If the key is a symbol it will match catches of the same symbol or of #t. If no catch matches, the `throw-default-handler' property of the key is checked. If it is bound to a procedure, that procedure is called: (handler key args ...) That procedure is called the "default handler". If there is no handler at all, or if the default handler returns to its caller, an error is signaled. It is traditional in Scheme to implement exception systems using `call-with-current-continuation', but his has not been done, for performance reaons. The implementation of `call-with-current-continuation' is a stack copying implementation. This allows it to interact well with ordinary C code. Unfortunately, a stack-copying implementation can be slow - creating a new continuation involves a block copy of the stack. Instead of using `call-with-current-continuation', the exception primitives are implemented as built-ins that take advantage of the *upward only* nature of exceptions. File: scm.info, Node: System Exceptions, Next: Variables, Prev: Exceptions, Up: Guile Facilities System Exceptions ================= These two expressions are equivalent: (error arg ...) (throw 'error arg ...) The following are the names of excpetions that may be thrown by the interpreter itself. ARGn "Wrong type argument" ARG1 "Wrong type argument in position 1" ARG2 "Wrong type argument in position 2" ARG3 "Wrong type argument in position 3" ARG4 "Wrong type argument in position 4" ARG5 "Wrong type argument in position 5" WNA "Wrong number of arguments" OVFLOW "Numerical overflow" OUTOFRANGE "Argument out of range" NALLOC "Could not allocate" HUP_SIGNAL "hang-up" INT_SIGNAL "user interrupt" FPE_SIGNAL "arithmetic error" BUS_SIGNAL "bus error" SEGV_SIGNAL "segmentation violation" ALRM_SIGNAL "alarm" read-sharp-error File: scm.info, Node: Variables, Next: User Defined Top Levels, Prev: System Exceptions, Up: Guile Facilities Variables ========= All top level bindings are stored in locations called "variables". Variables are first class objects. - Function: make-variable INIT - Function: make-variable INIT NAME-HINT Return a new variable, bound to INIT. The optional NAME-HINT is a symbolic name for the variable. It will be used in some error messages relating to the variable. - Function: variable-ref VARIABLE Return the current binding of VARIABLE. It is an error to call `variable-ref' on a variable which is unbound. - Function: variable-set! VARIABLE VALUE Modify the binding of VARIABLE. - Function: builtin-variable NAME Return the built-in variable for named NAME. NAME must be a symbol. Even symbols with no top level bindings have built-in variables. There is an unbounded supply of undefined variables. - Predicate: variable? OBJ Return `#t' if OBJ is a variable; `#f' otherwise. - Predicate: variable-bound? VAR Return `#t' if VAR is a bound variable; `#f' otherwise. - Function: make-undefined - Function: make-undefined NAME-HINT Return a new variable, initially unbound. The optional NAME-HINT a symbolic name for the variable. It will be used in some error messages relating to the variable. File: scm.info, Node: User Defined Top Levels, Next: Obarrays, Prev: Variables, Up: Guile Facilities User Defined Top Levels ======================= Low level support is provided for multiple top levels. This procedure should only be used advisadly. Most people should stick to the "user level module system interface". - Function: eval2 FORM ENV-FN Evaluate FORM in the top level environment described by ENV-FN. ENV-FN is called this way: (env-fn name defining) Return a variable object for the symbol NAME. Returning `#f' indicates that NAME has no binding. The boolean DEFINING is `#t', then the lookup is for a `define' form or the equivalent - a new variable may be created if none already exists. If `#f', then the request should not create a new binding. File: scm.info, Node: Obarrays, Next: Keywords, Prev: User Defined Top Levels, Up: Guile Facilities Obarrays ======== An "obarray" is an ordinary Scheme vector, used in a particular way. It represents two mapping: a mapping of strings to symbols, and a mapping of symbols to arbitrary values. To initialize an obarray, create a vector of any non-0 size, filled with the empty list. Thereafter, referring to the contents of the vector yields unspecified values. (You might be able guess the detailed representation of obarrays by examining the array, but if your code depends on that representation, it might easily break in future versions of Guile.) - Function: intern-string OBARRAY NAME Return the SYMBOL bound to the stringNAME in OBARRAY. If there is no such symbol, a new SYMBOL is allocated. OBARRAY may be `#f' which guarantees that a new SYMBOL is returned. - Function: intern-symbol OBARRAY SYMBOL Add SYMBOL to OBARRAY. If SYMBOL is already present, this has no effect. After this addition, SYMBOL is the symbol binding of its name. That is, even if another symbol of the same name was previously interned in OBARRAY, SYMBOL becomes the binding of that name after intern-symbol. (This does not mean that the previous symbol is removed from the OBARRAY). - Function: symbol-interned? OBARRAY SYMBOL Return `#t' if SYMBOL is in OBARRAY. - Function: symbol-bound? OBARRAY SYMBOL - Function: symbol-binding OBARRAY SYMBOL - Function: symbol-set! OBARRAY SYMBOL VALUE A SYMBOL in an OBARRAY may be bound arbitrarily. The binding may be changed. When first interned, a symbol is unbound. File: scm.info, Node: Keywords, Next: Procedure Properties, Prev: Obarrays, Up: Guile Facilities Keywords ======== A "keyword" is a self-evaluating symbol-like object with a convenient read syntax. (keyword? :keyword) => #t - Function: make-keyword SYMBOL Construct a keyword form a symbol. The first character of the symbol's name must be '-'. (make-keyword '-command) => :command - Function: keyword? OBJ Return `#f' unless OBJ is a keyword object. - Function: keyword->symbol KEYWORD Return the symbol that corresponds to a keyword. (keyword->symbol :text) => -text File: scm.info, Node: Procedure Properties, Next: Dynamic Roots, Prev: Keywords, Up: Guile Facilities Procedure Properties ==================== Procedures created using "define" or "lambda" have a binding slot which you can use arbitrarily. Many parts of the system will presume that this slot will contain a (possible empty) assoc list, keyed by symbols (`procedure properties'). If your procedure will be manipulated by a part of the system which is documented as using property lists, you should follow the convention, and use a unique prefix for all property names that you define. Procedures which do not escape to such parts of the system can hve any value at all in their binding slot. It is an arbitrary restriction that (some) built-in procedures lack a binding slot. This ought to be fixed. The reason it hasn't been fixed already is that the representation of the binding slot has to be chosen carefully for built-in procedure types. - Function: procedure-properties PROCEDURE - Function: set-procedure-properties! PROCEDURE VALUE Return or set the value held in a procedures binding slow. - Function: procedure-property PROC KEY - Function: procedure-assoc PROC KEY - Function: procedure-putprop! PROC KEY VALUE Retrieve or get the binding of a particular procedure property. These functions assume that the binding slot of the procedure holds an assoc list. `procedure-property' returns the binding of the property while `procedure-assoc' returns the key-value pair that holds the binding. File: scm.info, Node: Dynamic Roots, Next: Tcl Facilities, Prev: Procedure Properties, Up: Guile Facilities Dynamic Roots ============= A "dynamic root" is a root frame of Scheme evaluation. The top-level repl, for example, is an instance of a dynamic root. Each dynamic root has its own chain of dynamic-wind information. Each has its own set of continuations, jump-buffers, and pending CATCH statements which are inaccessible from the dynamic scope of any other dynamic root. In a thread-based system, each thread has its own dynamic root. Therefore, continuations created by one thread may not be invoked by another. [Thread support is not yet fully implemented.] Even in a single-threaded system, it is sometimes useful to create a new dynamic root. For example, if you want to apply a procedure, but to not allow that procedure to capture the current continuation, calling the procedure under a new dynamic root will do the job. - Function: call-with-dynamic-root THUNK ERROR-THUNK Evaluate (THUNK) in a new dynamic context, returning its value. If an error occurs during evaluation, call error-thunk, passing it an error code describing the condition. [Error codes are currently meaningless integers. In the future, real values will be specified.] If this happens, the error-thunk is called outside the scope of the new root - it is called in the same dynamic context in which call-with-dynamic-root was evaluated. If THUNK captures a continuation, the continuation is rooted at the call to THUNK. In particular, the call to call-with-dynamic-root is not captured. Therefore, call-with-dynamic-root always returns at most one time. Before calling THUNK, the dynamic-wind chain is un-wound back to the root and a new chain started for THUNK. Therefore, this call may not do what you expect: ;; Almost certainly a bug: (call-with-output-to-port some-port (lambda () (call-with-dynamic-root (lambda () (display 'fnord) (newline)) (lambda (errcode) errcode)))) The problem is, on what port will `fnord\n' be displayed? You might expect that because of the `call-with-input-from-port' that it will be displayed on the port bound to `some-port'. But it probably won't - before evaluating the thunk, dynamic winds are unwound, including those created by `call-with-input-from-port'. So, the standard output port will have been re-set to its default value before `display' is evaluated. (This function was added to Guile mostly to help calls to functions in C libraries that can not tolerate non-local exits or calls that return multiple times. If such functions call back to the interpreter, it should be under a new dynamic root.) - Function: dynamic-root Return an object representing the current dynamic root. These objects are only useful for comparison using `eq?'. They are currently represented as numbers, but your code should in no way depend on this. File: scm.info, Node: Tcl Facilities, Next: Tk Facilities, Prev: Dynamic Roots, Up: Guile Facilities Tcl Facilities ============== If you have Tcl extension modules written in C, these can be accessed from Guile programs. If you have an application that uses the Tcl interpreter, you can use Guile to define new modules for it - modules that can be loaded without having to re-compile. Documented here are the low-level facilities linking Tcl to Guile. In the future, a friendlier Scheme interface will be provided in preference to these entry points. - Function: tcl-create-interp Return a new Tcl interpreter object. An interpreter object is a namespace of functions and variables managed by modules that use the Tcl calling conventions. - Function: tcl-global-eval INTERPRETER STRING Evaluate a string according to Tcl's evaluation rules. INTERPRETER must be an object returned by `tcl-create-interp'. The return value is an integer/string pair. The integer is the Tcl status code, the string is the Tcl result. This is not the way to call a Tcl command. See the functions `tcl-command' and `tcl-apply-command'. Using those functions is faster. N.B.: by default, most built-in Tcl commands are absent in Guile. Consequently, most Tcl programs will not run. However, facilities exist so that you can link all of libtcl with Guile programs - in which case all the usual built-in commands will be present. [add reference!] - Function: tcl-get-int INTERPRETER STRING - Function: tcl-get-double INTERPRETER STRING - Function: tcl-get-boolean INTERPRETER STRING Convert strings to Scheme types according to the conventions of Tcl. - Function: tcl-split-list INTERPRETER STRING Split a Tcl-style "list" (a string following Tcl's list syntax) into a list. - Function: tcl-merge INTERPRETER LIST Combine a list of strings into a string following Tcl's list syntax. - Function: tcl-create-command INTERPRETER NAME PROCEDURE Define a new Tcl command which is recognized by the Tcl evaluator. INTERPRETER must be an object returned by `tcl-create-command'. NAME must be a string which is a valid Tcl identifier. PROCEDURE may be any Scheme procedure object. When the Tcl evaluator invokes the new command, PROCEDURE is called with as many arguments as were passed to the Tcl command. The arguments are all passed as strings. The return value of PROCEDURE is used as the Tcl result. The return value of PROCEDURE determines the Tcl return value according to these rules: if PROCEDURE returns: the Tcl result is: and Tcl status is: __________________________________________________________________ string (e.g. "foo") that string ("foo") TCL_OK integer (e.g. 1) the empty string the int (1) an int/string pair the string the int (e.g. (1 . "bogus frob")) ("bogus frob") (1) - Function: tcl-delete-command INTERPRETER NAME Remove the named command from a Tcl interpreter. - Function: tcl-trace-var2 INTERPRETER NAME INDEX FLAGS PROCEDURE - Function: tcl-untrace-var2 INTERPRETER NAME INDEX FLAGS PROCEDURE Add a callback to a Tcl variable. NAME is the name of the variable. INDEX is the subscript of the variable, or `#f' for a scalar. After `tcl-trace-var2', modifications to the named variable or array position cause procedure to be called with four arguments: a tcl interpreter, the variable being modified, an index into the named variable (possible the empty string), and an integer of flags. - Function: tcl-set-var2 INTERPRETER NAME INDEX VALUE FLAGS - Function: tcl-get-var2 INTERPRETER NAME INDEX FLAGS Set or return the current value of a Tcl variable. Symbolic names for Tcl flags are provided in the source file Gtcl.scm and are the same as their C counterparts. The procedure `flags' is used to combine flags. For example: (flags TCL_TRACE_READS TCL_TRACE_WRITES TCL_TRACE_UNSETS) Tcl commands can be invoked from Scheme directly, without having to use the Tcl evaluator: - Function: tcl-command INTERPRETER NAME Return an object representing the named command (or #f if none is defined). - Function: tcl-apply-command COMMAND ARGS Apply Tcl command COMMAND to the list of strings ARGS. COMMAND should be an object returned by `tcl-command'. ARGS should be a list of arguments. The return value is an integer/string pair. The integer is a Tcl return code, the string the Tcl result. The arguments can be of several types but must ultimately be converted to strings because of the way Tcl and Tk work internally. Types are converted this way: ;;---------------------------------------- ;; Argument Converted argument ;;---------------------------------------- 123 "123" 123.34 "123.34" "a-string" "a-string" 'a-symbol "a-symbol" :keyword "-keyword" #t "1" #f "0" (lambda (...) ...) "*__guile#234" The automatic conversion of a procedure works this way. First, a new Tcl name is generated for the procedure and a Tcl command with that name is defined. When evaluated, the Tcl command calls the Scheme procedure. Second, if the procedure has a property defined called 'tcl-calling-convention, and if that is bound to a string, then that string is appended to the name with an intervening space. For example, if a procedure's properties bind 'tcl-calling-convention to "%x %y", then the name is appended and winds up like "__guile#234 %x %y". Finally, an asterix is prepended to the name (e.g. "*__guile#234 %x %y"). In the GNU modified version of Tcl/Tk, an asterix prepended to a command name has special meaning if the name is passed as a "-command" or similar configuration parameter to a widget, or if passed as the command argument to a "bind" operation. In that case, the command is renamed to a canonical name that is unique to the widget or binding sequence (overwriting any previous definition). If the widget or binding sequence is later deleted, so is the canonicalized command. This is an extremely twisted way to trick Tcl into managing anonymous Scheme procedures with acceptable semantics (e.g., without core leaks and without requiring Scheme programmers to invent liveness for anonymous procedures they'd otherwise drop). File: scm.info, Node: Tk Facilities, Next: Gwish, Prev: Tcl Facilities, Up: Guile Facilities Tk Facilities ============= So that Tk widgets can be used form Scheme, Guile provides the following functions: - Function: tk-init-main-window INTERPRETER DISPLAY NAME CLASS Initialize a Tcl interpreter as a Tk main window. DISPLAY, NAME, and CLASS must all be strings. - Function: tk-do-one-event FLAGS Process one window system event. Symbolic definitions for FLAGS are provided in Gtk.scm and have the same name as their C counterparts. - Function: tk-main-loop Process window events until no windows remain.